<!DOCTYPE html>
<html id="docs" lang="en" class="">
	<head>
	<meta charset="utf-8">
<title>StatefulSets - Kubernetes</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="shortcut icon" type="image/png" href="../../../../../images/favicon.png">
<link rel="stylesheet" type="text/css" href="../../../../../css/base_fonts.css">
<link rel="stylesheet" type="text/css" href="../../../../../css/styles.css">
<link rel="stylesheet" type="text/css" href="https://code.jquery.com/ui/1.12.1/themes/smoothness/jquery-ui.css">
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.css">
<link rel="stylesheet" type="text/css" href="../../../../../css/callouts.css">
<link rel="stylesheet" type="text/css" href="../../../../../css/custom-jekyll/tags.css">




<meta name="description" content="StatefulSets" />
<meta property="og:description" content="StatefulSets" />

<meta property="og:url" content="https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/" />
<meta property="og:title" content="StatefulSets - Kubernetes" />

<script
src="https://code.jquery.com/jquery-3.2.1.min.js"
integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4="
crossorigin="anonymous"></script>
<script
src="https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"
integrity="sha256-VazP97ZCwtekAsvgPBSUwPFKdrwD3unUfSGVYrahUqU="
crossorigin="anonymous"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/sweetalert/1.1.3/sweetalert.min.js"></script>
<script src="../../../../../js/script.js"></script>
<script src="../../../../../js/custom-jekyll/tags.js"></script>


	</head>
	<body>
		<div id="cellophane" onclick="kub.toggleMenu()"></div>

<header>
    <a href="../../../../../index.html" class="logo"></a>

    <div class="nav-buttons" data-auto-burger="primary">
        <ul class="global-nav">
            
            
            <li><a href="../../../../home.1">Documentation</a></li>
            
            <li><a href="../../../../../blog/index.html">Blog</a></li>
            
            <li><a href="../../../../../partners/index.html">Partners</a></li>
            
            <li><a href="../../../../../community/index.html">Community</a></li>
            
            <li><a href="../../../../../case-studies/index.html">Case Studies</a></li>
            
            
             <li>
                <a href="../statefulset.md#">
                    English <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="../../../../../zh/index.html">中文 Chinese</a></li>
                
                    <li><a href="../../../../../ko/index.html">한국어 Korean</a></li>
                
                </ul>
            </li>
         
            <li>
                <a href="../statefulset.md#">
                    v1.11 <span class="ui-icon ui-icon-carat-1-s"></span>
                </a>
                <ul>
                
                    <li><a href="https://kubernetes.io">v1.12</a></li>
                
                    <li><a href="../../../../../index.html">v1.11</a></li>
                
                    <li><a href="https://v1-10.docs.kubernetes.io">v1.10</a></li>
                
                    <li><a href="https://v1-9.docs.kubernetes.io">v1.9</a></li>
                
                </ul>
            </li>
        </ul>
        
        <a href="../../../../tutorials/kubernetes-basics/index.html" class="button" id="tryKubernetes" data-auto-burger-exclude>Try Kubernetes</a>
        <button id="hamburger" onclick="kub.toggleMenu()" data-auto-burger-exclude><div></div></button>
    </div>

    <nav id="mainNav">
        <main data-auto-burger="primary">
        <div class="nav-box">
            <h3><a href="../../../../tutorials/stateless-application/hello-minikube/index.html">Get Started</a></h3>
            <p>Ready to get your hands dirty? Build a simple Kubernetes cluster that runs "Hello World" for Node.js.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../../home.1">Documentation</a></h3>
            <p>Learn how to use Kubernetes with the use of walkthroughs, samples, and reference documentation. You can even <a href="../../../../../editdocs/index.html" data-auto-burger-exclude>help contribute to the docs</a>!</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../../../community/index.html">Community</a></h3>
            <p>If you need help, you can connect with other Kubernetes users and the Kubernetes authors, attend community events, and watch video presentations from around the web.</p>
        </div>
        <div class="nav-box">
            <h3><a href="../../../../../blog/index.html">Blog</a></h3>
            <p>Read the latest news for Kubernetes and the containers space in general, and get technical how-tos hot off the presses.</p>
        </div>
        </main>
        <main data-auto-burger="primary">
        <div class="left">
            <h5 class="github-invite">Interested in hacking on the core Kubernetes code base?</h5>
            <a href="https://github.com/kubernetes/kubernetes" class="button" data-auto-burger-exclude>View On Github</a>
        </div>

        <div class="right">
            <h5 class="github-invite">Explore the community</h5>
            <div class="social">
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>Twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
        </div>
        <div class="clear" style="clear: both"></div>
        </main>
    </nav>
</header>

		
		
		<section id="hero" class="light-text no-sub">
			









<h1>Concepts</h1>
<h5></h5>








<div id="vendorStrip" class="light-text">
	<ul>
		
		
		<li><a href="../../../../home.1">DOCUMENTATION</a></li>
		
		
		<li><a href="../../../../setup/index.html">SETUP</a></li>
		
		
		<li><a href="../../../index.html" class="YAH">CONCEPTS</a></li>
		
		
		<li><a href="../../../../tasks/index.html">TASKS</a></li>
		
		
		<li><a href="../../../../tutorials/index.html">TUTORIALS</a></li>
		
		
		<li><a href="../../../../reference.1">REFERENCE</a></li>
		
	</ul>
	<div id="searchBox">
		<input type="text" id="search" placeholder="Search" onkeydown="if (event.keyCode==13) window.location.replace('/docs/search/?q=' + this.value)" autofocus="autofocus">
	</div>
</div>

		</section>
		
		
<section id="deprecationWarning">
  <main>
    <div class="content deprecation-warning">
      <h3>
        Documentation for Kubernetes v1.11 is no longer actively maintained. The version you are currently viewing is a static snapshot.
        For up-to-date documentation, see the <a href="https://kubernetes.io/docs/home/">latest</a> version.
      </h3>
    </div>
  </main>
</section>


		<section id="encyclopedia">
			
<div id="docsToc">
     <div class="pi-accordion">
    	
        
        
        
        
        
         
             
                 
             
         
             
                 
             
         
             
                 
                          
                          
                 
             
         
             
         
             
         
             
         
             
         
             
         
         
        
        <a class="item" data-title="Concepts" href="../../../index.html"></a>

	
	
		
		
	<div class="item" data-title="Overview">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="What is Kubernetes?" href="../../../overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Kubernetes Components" href="../../../overview/components.1"></a>

		
	
		
		
<a class="item" data-title="The Kubernetes API" href="../../../overview/kubernetes-api/index.html"></a>

		
	
		
		
	<div class="item" data-title="Working with Kubernetes Objects">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Understanding Kubernetes Objects" href="../../../overview/working-with-objects/kubernetes-objects.1"></a>

		
	
		
		
<a class="item" data-title="Names" href="../../../../user-guide/identifiers"></a>

		
	
		
		
<a class="item" data-title="Namespaces" href="../../../overview/working-with-objects/namespaces.1"></a>

		
	
		
		
<a class="item" data-title="Labels and Selectors" href="../../../../user-guide/labels"></a>

		
	
		
		
<a class="item" data-title="Annotations" href="../../../overview/working-with-objects/annotations.1"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Object Management Using kubectl">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Kubernetes Object Management" href="../../../../tutorials/object-management-kubectl/object-management/index.html"></a>

		
	
		
		
<a class="item" data-title="Managing Kubernetes Objects Using Imperative Commands" href="../../../../tutorials/object-management-kubectl/imperative-object-management-command/index.html"></a>

		
	
		
		
<a class="item" data-title="Imperative Management of Kubernetes Objects Using Configuration Files" href="../../../../tutorials/object-management-kubectl/imperative-object-management-configuration/index.html"></a>

		
	
		
		
<a class="item" data-title="Declarative Management of Kubernetes Objects Using Configuration Files" href="../../../../tutorials/object-management-kubectl/declarative-object-management-configuration/index.html"></a>

		
	

		</div>
	</div>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Compute, Storage, and Networking Extensions">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Cluster Administration Overview" href="../../../cluster-administration/cluster-administration-overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Certificates" href="../../../cluster-administration/certificates/index.html"></a>

		
	
		
		
<a class="item" data-title="Cloud Providers" href="../../../cluster-administration/cloud-providers/index.html"></a>

		
	
		
		
<a class="item" data-title="Managing Resources" href="../../../cluster-administration/manage-deployment/index.html"></a>

		
	
		
		
<a class="item" data-title="Cluster Networking" href="../../../../admin/networking"></a>

		
	
		
		
<a class="item" data-title="Logging Architecture" href="../../../cluster-administration/logging.1"></a>

		
	
		
		
<a class="item" data-title="Configuring kubelet Garbage Collection" href="../../../cluster-administration/kubelet-garbage-collection/index.html"></a>

		
	
		
		
<a class="item" data-title="Federation" href="../../../cluster-administration/federation/index.html"></a>

		
	
		
		
<a class="item" data-title="Proxies in Kubernetes" href="../../../cluster-administration/proxies/index.html"></a>

		
	
		
		
<a class="item" data-title="Controller manager metrics" href="../../../cluster-administration/controller-metrics/index.html"></a>

		
	
		
		
<a class="item" data-title="Installing Addons" href="../../../cluster-administration/addons/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Kubernetes Architecture">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Nodes" href="../../../../admin/node.1"></a>

		
	
		
		
<a class="item" data-title="Master-Node communication" href="../../../architecture/master-node-communication/index.html"></a>

		
	
		
		
<a class="item" data-title="Concepts Underlying the Cloud Controller Manager" href="../../../architecture/cloud-controller/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Extending Kubernetes">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Extending your Kubernetes Cluster" href="../../../overview/extending/index.html"></a>

		
	
		
		
	<div class="item" data-title="Extending the Kubernetes API">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Extending the Kubernetes API with the aggregation layer" href="../../../api-extension/apiserver-aggregation.1"></a>

		
	
		
		
<a class="item" data-title="Custom Resources" href="../../../api-extension/custom-resources/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Compute, Storage, and Networking Extensions">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Network Plugins" href="../../../../admin/network-plugins/index.html"></a>

		
	
		
		
<a class="item" data-title="Device Plugins" href="../../../cluster-administration/device-plugins.1"></a>

		
	

		</div>
	</div>

		
	
		
		
<a class="item" data-title="Service Catalog" href="../../../service-catalog/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Containers">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Images" href="../../../containers/images/index.html"></a>

		
	
		
		
<a class="item" data-title="Container Environment Variables" href="../../../containers/container-environment-variables/index.html"></a>

		
	
		
		
<a class="item" data-title="Container Lifecycle Hooks" href="../../../containers/container-lifecycle-hooks/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Workloads">
		<div class="container">
		
		
	
	
		
		
	<div class="item" data-title="Pods">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Pod Overview" href="../../pods/pod-overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Pods" href="../../../../user-guide/pods/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Lifecycle" href="../../../../user-guide/pod-states/index.html"></a>

		
	
		
		
<a class="item" data-title="Init Containers" href="../../../abstractions/init-containers/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Preset" href="../../pods/podpreset/index.html"></a>

		
	
		
		
<a class="item" data-title="Disruptions" href="../../pods/disruptions/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Controllers">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="ReplicaSet" href="../replicaset/index.html"></a>

		
	
		
		
<a class="item" data-title="ReplicationController" href="../../../../user-guide/replication-controller/index.html"></a>

		
	
		
		
<a class="item" data-title="Deployments" href="../deployment/index.html"></a>

		
	
		
		
<a class="item" data-title="StatefulSets" href="../statefulset.md"></a>

		
	
		
		
<a class="item" data-title="DaemonSet" href="../daemonset.1"></a>

		
	
		
		
<a class="item" data-title="Garbage Collection" href="../garbage-collection/index.html"></a>

		
	
		
		
<a class="item" data-title="Jobs - Run to Completion" href="../jobs-run-to-completion.1"></a>

		
	
		
		
<a class="item" data-title="CronJob" href="../cron-jobs.1"></a>

		
	

		</div>
	</div>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Configuration">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Configuration Best Practices" href="../../../configuration/overview/index.html"></a>

		
	
		
		
<a class="item" data-title="Managing Compute Resources for Containers" href="../../../../user-guide/compute-resources/index.html"></a>

		
	
		
		
<a class="item" data-title="Assigning Pods to Nodes" href="../../../../user-guide/node-selection/index.html"></a>

		
	
		
		
<a class="item" data-title="Taints and Tolerations" href="../../../configuration/taint-and-toleration.1"></a>

		
	
		
		
<a class="item" data-title="Secrets" href="../../../../user-guide/secrets.1"></a>

		
	
		
		
<a class="item" data-title="Organizing Cluster Access Using kubeconfig Files" href="../../../configuration/organize-cluster-access-kubeconfig/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Priority and Preemption" href="../../../configuration/pod-priority-preemption/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Services, Load Balancing, and Networking">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Services" href="../../../../user-guide/services"></a>

		
	
		
		
<a class="item" data-title="DNS for Services and Pods" href="../../../services-networking/dns-pod-service/index.html"></a>

		
	
		
		
<a class="item" data-title="Connecting Applications with Services" href="../../../services-networking/connect-applications-service.1"></a>

		
	
		
		
<a class="item" data-title="Ingress" href="../../../services-networking/ingress/index.html"></a>

		
	
		
		
<a class="item" data-title="Network Policies" href="../../../services-networking/networkpolicies/index.html"></a>

		
	
		
		
<a class="item" data-title="Adding entries to Pod /etc/hosts with HostAliases" href="../../../services-networking/add-entries-to-pod-etc-hosts-with-host-aliases/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Storage">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Volumes" href="../../../storage/volumes.1"></a>

		
	
		
		
<a class="item" data-title="Persistent Volumes" href="../../../../user-guide/persistent-volumes/index.html"></a>

		
	
		
		
<a class="item" data-title="Storage Classes" href="../../../storage/storage-classes.1"></a>

		
	
		
		
<a class="item" data-title="Dynamic Volume Provisioning" href="../../../storage/dynamic-provisioning/index.html"></a>

		
	
		
		
<a class="item" data-title="Node-specific Volume Limits" href="../../../storage/storage-limits/index.html"></a>

		
	

		</div>
	</div>

		
	
		
		
	<div class="item" data-title="Policies">
		<div class="container">
		
		
	
	
		
		
<a class="item" data-title="Resource Quotas" href="../../../policy/resource-quotas/index.html"></a>

		
	
		
		
<a class="item" data-title="Pod Security Policies" href="../../../../user-guide/pod-security-policy"></a>

		
	

		</div>
	</div>

		
	






     </div> 
    <button class="push-menu-close-button" onclick="kub.toggleToc()"></button>
</div> 

			<div id="docsContent">
				
<p><a href="../../../../editdocs#docs/concepts/workloads/controllers/statefulset.md" id="editPageButton">Edit This Page</a></p>

<h1>StatefulSets</h1>



<p>StatefulSet is the workload API object used to manage stateful applications.</p>

<blockquote class="note">
  <div><strong>Note:</strong> StatefulSets are stable (GA) in 1.9.</div>
</blockquote>

<p>Manages the deployment and scaling of a set of <a class='glossary-tooltip' href='../../pods/pod-overview/index.html' target='_blank'>Pods<span class='tooltip-text'>The smallest and simplest Kubernetes object. A Pod represents a set of running containers on your cluster.</span>
</a>, <em>and provides guarantees about the ordering and uniqueness</em> of these Pods.</p>

<p></p>

<p>Like a <a class='glossary-tooltip' href='../deployment/index.html' target='_blank'>Deployment<span class='tooltip-text'>An API object that manages a replicated application.</span>
</a>, a StatefulSet manages Pods that are based on an identical container spec. Unlike a Deployment, a StatefulSet maintains a sticky identity for each of their Pods. These pods are created from the same spec, but are not interchangeable&#58; each has a persistent identifier that it maintains across any rescheduling.</p>

<p>A StatefulSet operates under the same pattern as any other Controller. You define your desired state in a StatefulSet <em>object</em>, and the StatefulSet <em>controller</em> makes any necessary updates to get there from the current state.</p>









<ul id="markdown-toc">










<li><a href="../statefulset.md#using-statefulsets">Using StatefulSets</a></li>




<li><a href="../statefulset.md#limitations">Limitations</a></li>




<li><a href="../statefulset.md#components">Components</a></li>




<li><a href="../statefulset.md#pod-selector">Pod Selector</a></li>




<li><a href="../statefulset.md#pod-identity">Pod Identity</a></li>




<li><a href="../statefulset.md#deployment-and-scaling-guarantees">Deployment and Scaling Guarantees</a></li>




<li><a href="../statefulset.md#update-strategies">Update Strategies</a></li>




















<li><a href="../statefulset.md#what-s-next">What's next</a></li>



</ul>


<h2 id="using-statefulsets">Using StatefulSets</h2>

<p>StatefulSets are valuable for applications that require one or more of the
following.</p>

<ul>
<li>Stable, unique network identifiers.</li>
<li>Stable, persistent storage.</li>
<li>Ordered, graceful deployment and scaling.</li>
<li>Ordered, graceful deletion and termination.</li>
<li>Ordered, automated rolling updates.</li>
</ul>

<p>In the above, stable is synonymous with persistence across Pod (re)scheduling.
If an application doesn&rsquo;t require any stable identifiers or ordered deployment,
deletion, or scaling, you should deploy your application with a controller that
provides a set of stateless replicas. Controllers such as
<a href="../deployment/index.html">Deployment</a> or
<a href="../replicaset/index.html">ReplicaSet</a> may be better suited to your stateless needs.</p>

<h2 id="limitations">Limitations</h2>

<ul>
<li>StatefulSet was a beta resource prior to 1.9 and not available in any Kubernetes release prior to 1.5.</li>
<li>As with all alpha/beta resources, you can disable StatefulSet through the <code>--runtime-config</code> option passed to the apiserver.</li>
<li>The storage for a given Pod must either be provisioned by a <a href="https://github.com/kubernetes/examples/tree/v1.11.3/staging/persistent-volume-provisioning/README.md" target="_blank">PersistentVolume Provisioner</a> based on the requested <code>storage class</code>, or pre-provisioned by an admin.</li>
<li>Deleting and/or scaling a StatefulSet down will <em>not</em> delete the volumes associated with the StatefulSet. This is done to ensure data safety, which is generally more valuable than an automatic purge of all related StatefulSet resources.</li>
<li>StatefulSets currently require a <a href="../../../../user-guide/services#headless-services">Headless Service</a> to be responsible for the network identity of the Pods. You are responsible for creating this Service.</li>
</ul>

<h2 id="components">Components</h2>

<p>The example below demonstrates the components of a StatefulSet.</p>

<ul>
<li>A Headless Service, named nginx, is used to control the network domain.</li>
<li>The StatefulSet, named web, has a Spec that indicates that 3 replicas of the nginx container will be launched in unique Pods.</li>
<li>The volumeClaimTemplates will provide stable storage using <a href="../../../../user-guide/persistent-volumes/index.html">PersistentVolumes</a> provisioned by a PersistentVolume Provisioner.</li>
</ul>
<div class="highlight"><pre style="background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-yaml" data-lang="yaml">apiVersion:<span style="color:#bbb"> </span>v1<span style="color:#bbb">
</span><span style="color:#bbb"></span>kind:<span style="color:#bbb"> </span>Service<span style="color:#bbb">
</span><span style="color:#bbb"></span>metadata:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>name:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb">  </span>labels:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>app:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb"></span>spec:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>ports:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>-<span style="color:#bbb"> </span>port:<span style="color:#bbb"> </span><span style="color:#666">80</span><span style="color:#bbb">
</span><span style="color:#bbb">    </span>name:<span style="color:#bbb"> </span>web<span style="color:#bbb">
</span><span style="color:#bbb">  </span>clusterIP:<span style="color:#bbb"> </span>None<span style="color:#bbb">
</span><span style="color:#bbb">  </span>selector:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>app:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb"></span>---<span style="color:#bbb">
</span><span style="color:#bbb"></span>apiVersion:<span style="color:#bbb"> </span>apps/v1<span style="color:#bbb">
</span><span style="color:#bbb"></span>kind:<span style="color:#bbb"> </span>StatefulSet<span style="color:#bbb">
</span><span style="color:#bbb"></span>metadata:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>name:<span style="color:#bbb"> </span>web<span style="color:#bbb">
</span><span style="color:#bbb"></span>spec:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>selector:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>matchLabels:<span style="color:#bbb">
</span><span style="color:#bbb">      </span>app:<span style="color:#bbb"> </span>nginx<span style="color:#bbb"> </span><span style="color:#080;font-style:italic"># has to match .spec.template.metadata.labels</span><span style="color:#bbb">
</span><span style="color:#bbb">  </span>serviceName:<span style="color:#bbb"> </span><span style="color:#b44">&#34;nginx&#34;</span><span style="color:#bbb">
</span><span style="color:#bbb">  </span>replicas:<span style="color:#bbb"> </span><span style="color:#666">3</span><span style="color:#bbb"> </span><span style="color:#080;font-style:italic"># by default is 1</span><span style="color:#bbb">
</span><span style="color:#bbb">  </span>template:<span style="color:#bbb">
</span><span style="color:#bbb">    </span>metadata:<span style="color:#bbb">
</span><span style="color:#bbb">      </span>labels:<span style="color:#bbb">
</span><span style="color:#bbb">        </span>app:<span style="color:#bbb"> </span>nginx<span style="color:#bbb"> </span><span style="color:#080;font-style:italic"># has to match .spec.selector.matchLabels</span><span style="color:#bbb">
</span><span style="color:#bbb">    </span>spec:<span style="color:#bbb">
</span><span style="color:#bbb">      </span>terminationGracePeriodSeconds:<span style="color:#bbb"> </span><span style="color:#666">10</span><span style="color:#bbb">
</span><span style="color:#bbb">      </span>containers:<span style="color:#bbb">
</span><span style="color:#bbb">      </span>-<span style="color:#bbb"> </span>name:<span style="color:#bbb"> </span>nginx<span style="color:#bbb">
</span><span style="color:#bbb">        </span>image:<span style="color:#bbb"> </span>k8s.gcr.io/nginx-slim:<span style="color:#666">0.8</span><span style="color:#bbb">
</span><span style="color:#bbb">        </span>ports:<span style="color:#bbb">
</span><span style="color:#bbb">        </span>-<span style="color:#bbb"> </span>containerPort:<span style="color:#bbb"> </span><span style="color:#666">80</span><span style="color:#bbb">
</span><span style="color:#bbb">          </span>name:<span style="color:#bbb"> </span>web<span style="color:#bbb">
</span><span style="color:#bbb">        </span>volumeMounts:<span style="color:#bbb">
</span><span style="color:#bbb">        </span>-<span style="color:#bbb"> </span>name:<span style="color:#bbb"> </span>www<span style="color:#bbb">
</span><span style="color:#bbb">          </span>mountPath:<span style="color:#bbb"> </span>/usr/share/nginx/html<span style="color:#bbb">
</span><span style="color:#bbb">  </span>volumeClaimTemplates:<span style="color:#bbb">
</span><span style="color:#bbb">  </span>-<span style="color:#bbb"> </span>metadata:<span style="color:#bbb">
</span><span style="color:#bbb">      </span>name:<span style="color:#bbb"> </span>www<span style="color:#bbb">
</span><span style="color:#bbb">    </span>spec:<span style="color:#bbb">
</span><span style="color:#bbb">      </span>accessModes:<span style="color:#bbb"> </span>[<span style="color:#bbb"> </span><span style="color:#b44">&#34;ReadWriteOnce&#34;</span><span style="color:#bbb"> </span>]<span style="color:#bbb">
</span><span style="color:#bbb">      </span>storageClassName:<span style="color:#bbb"> </span><span style="color:#b44">&#34;my-storage-class&#34;</span><span style="color:#bbb">
</span><span style="color:#bbb">      </span>resources:<span style="color:#bbb">
</span><span style="color:#bbb">        </span>requests:<span style="color:#bbb">
</span><span style="color:#bbb">          </span>storage:<span style="color:#bbb"> </span>1Gi</code></pre></div>
<h2 id="pod-selector">Pod Selector</h2>

<p>You must set the <code>.spec.selector</code> field of a StatefulSet to match the labels of its <code>.spec.template.metadata.labels</code>. Prior to Kubernetes 1.8, the <code>.spec.selector</code> field was defaulted when omitted. In 1.8 and later versions, failing to specify a matching Pod Selector will result in a validation error during StatefulSet creation.</p>

<h2 id="pod-identity">Pod Identity</h2>

<p>StatefulSet Pods have a unique identity that is comprised of an ordinal, a
stable network identity, and stable storage. The identity sticks to the Pod,
regardless of which node it&rsquo;s (re)scheduled on.</p>

<h3 id="ordinal-index">Ordinal Index</h3>

<p>For a StatefulSet with N replicas, each Pod in the StatefulSet will be
assigned an integer ordinal, from 0 up through N-1, that is unique over the Set.</p>

<h3 id="stable-network-id">Stable Network ID</h3>

<p>Each Pod in a StatefulSet derives its hostname from the name of the StatefulSet
and the ordinal of the Pod. The pattern for the constructed hostname
is <code>$(statefulset name)-$(ordinal)</code>. The example above will create three Pods
named <code>web-0,web-1,web-2</code>.
A StatefulSet can use a <a href="../../../../user-guide/services#headless-services">Headless Service</a>
to control the domain of its Pods. The domain managed by this Service takes the form:
<code>$(service name).$(namespace).svc.cluster.local</code>, where &ldquo;cluster.local&rdquo; is the
cluster domain.
As each Pod is created, it gets a matching DNS subdomain, taking the form:
<code>$(podname).$(governing service domain)</code>, where the governing service is defined
by the <code>serviceName</code> field on the StatefulSet.</p>

<p>Here are some examples of choices for Cluster Domain, Service name,
StatefulSet name, and how that affects the DNS names for the StatefulSet&rsquo;s Pods.</p>

<table>
<thead>
<tr>
<th>Cluster Domain</th>
<th>Service (ns/name)</th>
<th>StatefulSet (ns/name)</th>
<th>StatefulSet Domain</th>
<th>Pod DNS</th>
<th>Pod Hostname</th>
</tr>
</thead>

<tbody>
<tr>
<td>cluster.local</td>
<td>default/nginx</td>
<td>default/web</td>
<td>nginx.default.svc.cluster.local</td>
<td>web-{0..N-1}.nginx.default.svc.cluster.local</td>
<td>web-{0..N-1}</td>
</tr>

<tr>
<td>cluster.local</td>
<td>foo/nginx</td>
<td>foo/web</td>
<td>nginx.foo.svc.cluster.local</td>
<td>web-{0..N-1}.nginx.foo.svc.cluster.local</td>
<td>web-{0..N-1}</td>
</tr>

<tr>
<td>kube.local</td>
<td>foo/nginx</td>
<td>foo/web</td>
<td>nginx.foo.svc.kube.local</td>
<td>web-{0..N-1}.nginx.foo.svc.kube.local</td>
<td>web-{0..N-1}</td>
</tr>
</tbody>
</table>

<p>Note that Cluster Domain will be set to <code>cluster.local</code> unless
<a href="../../../services-networking/dns-pod-service/index.html#how-it-works">otherwise configured</a>.</p>

<h3 id="stable-storage">Stable Storage</h3>

<p>Kubernetes creates one <a href="../../../../user-guide/persistent-volumes/index.html">PersistentVolume</a> for each
VolumeClaimTemplate. In the nginx example above, each Pod will receive a single PersistentVolume
with a StorageClass of <code>my-storage-class</code> and 1 Gib of provisioned storage. If no StorageClass
is specified, then the default StorageClass will be used. When a Pod is (re)scheduled
onto a node, its <code>volumeMounts</code> mount the PersistentVolumes associated with its
PersistentVolume Claims. Note that, the PersistentVolumes associated with the
Pods&rsquo; PersistentVolume Claims are not deleted when the Pods, or StatefulSet are deleted.
This must be done manually.</p>

<h3 id="pod-name-label">Pod Name Label</h3>

<p>When the StatefulSet controller creates a Pod, it adds a label, <code>statefulset.kubernetes.io/pod-name</code>,
that is set to the name of the Pod. This label allows you to attach a Service to a specific Pod in
the StatefulSet.</p>

<h2 id="deployment-and-scaling-guarantees">Deployment and Scaling Guarantees</h2>

<ul>
<li>For a StatefulSet with N replicas, when Pods are being deployed, they are created sequentially, in order from {0..N-1}.</li>
<li>When Pods are being deleted, they are terminated in reverse order, from {N-1..0}.</li>
<li>Before a scaling operation is applied to a Pod, all of its predecessors must be Running and Ready.</li>
<li>Before a Pod is terminated, all of its successors must be completely shutdown.</li>
</ul>

<p>The StatefulSet should not specify a <code>pod.Spec.TerminationGracePeriodSeconds</code> of 0. This practice is unsafe and strongly discouraged. For further explanation, please refer to <a href="../../../../tasks/run-application/force-delete-stateful-set-pod/index.html">force deleting StatefulSet Pods</a>.</p>

<p>When the nginx example above is created, three Pods will be deployed in the order
web-0, web-1, web-2. web-1 will not be deployed before web-0 is
<a href="../../../../user-guide/pod-states/index.html">Running and Ready</a>, and web-2 will not be deployed until
web-1 is Running and Ready. If web-0 should fail, after web-1 is Running and Ready, but before
web-2 is launched, web-2 will not be launched until web-0 is successfully relaunched and
becomes Running and Ready.</p>

<p>If a user were to scale the deployed example by patching the StatefulSet such that
<code>replicas=1</code>, web-2 would be terminated first. web-1 would not be terminated until web-2
is fully shutdown and deleted. If web-0 were to fail after web-2 has been terminated and
is completely shutdown, but prior to web-1&rsquo;s termination, web-1 would not be terminated
until web-0 is Running and Ready.</p>

<h3 id="pod-management-policies">Pod Management Policies</h3>

<p>In Kubernetes 1.7 and later, StatefulSet allows you to relax its ordering guarantees while
preserving its uniqueness and identity guarantees via its <code>.spec.podManagementPolicy</code> field.</p>

<h4 id="orderedready-pod-management">OrderedReady Pod Management</h4>

<p><code>OrderedReady</code> pod management is the default for StatefulSets. It implements the behavior
described <a href="../statefulset.md#deployment-and-scaling-guarantees">above</a>.</p>

<h4 id="parallel-pod-management">Parallel Pod Management</h4>

<p><code>Parallel</code> pod management tells the StatefulSet controller to launch or
terminate all Pods in parallel, and to not wait for Pods to become Running
and Ready or completely terminated prior to launching or terminating another
Pod.</p>

<h2 id="update-strategies">Update Strategies</h2>

<p>In Kubernetes 1.7 and later, StatefulSet&rsquo;s <code>.spec.updateStrategy</code> field allows you to configure
and disable automated rolling updates for containers, labels, resource request/limits, and
annotations for the Pods in a StatefulSet.</p>

<h3 id="on-delete">On Delete</h3>

<p>The <code>OnDelete</code> update strategy implements the legacy (1.6 and prior) behavior. When a StatefulSet&rsquo;s
<code>.spec.updateStrategy.type</code> is set to <code>OnDelete</code>, the StatefulSet controller will not automatically
update the Pods in a StatefulSet. Users must manually delete Pods to cause the controller to
create new Pods that reflect modifications made to a StatefulSet&rsquo;s <code>.spec.template</code>.</p>

<h3 id="rolling-updates">Rolling Updates</h3>

<p>The <code>RollingUpdate</code> update strategy implements automated, rolling update for the Pods in a
StatefulSet. It is the default strategy when <code>.spec.updateStrategy</code> is left unspecified. When a StatefulSet&rsquo;s <code>.spec.updateStrategy.type</code> is set to <code>RollingUpdate</code>, the
StatefulSet controller will delete and recreate each Pod in the StatefulSet. It will proceed
in the same order as Pod termination (from the largest ordinal to the smallest), updating
each Pod one at a time. It will wait until an updated Pod is Running and Ready prior to
updating its predecessor.</p>

<h4 id="partitions">Partitions</h4>

<p>The <code>RollingUpdate</code> update strategy can be partitioned, by specifying a
<code>.spec.updateStrategy.rollingUpdate.partition</code>. If a partition is specified, all Pods with an
ordinal that is greater than or equal to the partition will be updated when the StatefulSet&rsquo;s
<code>.spec.template</code> is updated. All Pods with an ordinal that is less than the partition will not
be updated, and, even if they are deleted, they will be recreated at the previous version. If a
StatefulSet&rsquo;s <code>.spec.updateStrategy.rollingUpdate.partition</code> is greater than its <code>.spec.replicas</code>,
updates to its <code>.spec.template</code> will not be propagated to its Pods.
In most cases you will not need to use a partition, but they are useful if you want to stage an
update, roll out a canary, or perform a phased roll out.</p>





<p>
</p>




<h2 id="what-s-next">What&#39;s next</h2>
<ul>
<li>Follow an example of <a href="../../../../tutorials/stateful-application/basic-stateful-set/index.html">deploying a stateful application</a>.</li>
<li>Follow an example of <a href="../../../../tutorials/stateful-application/cassandra/index.html">deploying Cassandra with Stateful Sets</a>.</li>
</ul>






				<div class="issue-button-container">
					<p><a href="../statefulset.md"><img src="https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/concepts/workloads/controllers/statefulset.md?pixel" alt="Analytics" /></a></p>
					
					
					<script type="text/javascript">
					PDRTJS_settings_8345992 = {
					"id" : "8345992",
					"unique_id" : "\/docs\/concepts\/workloads\/controllers\/statefulset\/",
					"title" : "StatefulSets",
					"permalink" : "https:\/\/kubernetes.io\/docs\/concepts\/workloads\/controllers\/statefulset\/"
					};
					(function(d,c,j){if(!document.getElementById(j)){var pd=d.createElement(c),s;pd.id=j;pd.src=('https:'==document.location.protocol)?'https://polldaddy.com/js/rating/rating.js':'http://i0.poll.fm/js/rating/rating.js';s=document.getElementsByTagName(c)[0];s.parentNode.insertBefore(pd,s);}}(document,'script','pd-rating-js'));
					</script>
					<a href="../statefulset.md" onclick="window.open('https://github.com/kubernetes/website/issues/new?title=Issue%20with%20' +
					'k8s.io'+window.location.pathname)" class="button issue">Create an Issue</a>
					
					
					
					<a href="../../../../editdocs#docs/concepts/workloads/controllers/statefulset.md" class="button issue">Edit this Page</a>
					
				</div>
			</div>
		</section>
		<footer>
    <main class="light-text">
        <nav>
            
            
            
            <a href="../../../../home.1">Documentation</a>
            
            <a href="../../../../../blog/index.html">Blog</a>
            
            <a href="../../../../../partners/index.html">Partners</a>
            
            <a href="../../../../../community/index.html">Community</a>
            
            <a href="../../../../../case-studies/index.html">Case Studies</a>
            
        </nav>
        <div class="social">
            <div>
                <a href="https://twitter.com/kubernetesio" class="twitter"><span>twitter</span></a>
                <a href="https://github.com/kubernetes/kubernetes" class="github"><span>Github</span></a>
                <a href="http://slack.k8s.io/" class="slack"><span>Slack</span></a>
            </div>
            <div>
                <a href="http://stackoverflow.com/questions/tagged/kubernetes" class="stack-overflow"><span>Stack Overflow</span></a>
                <a href="https://discuss.kubernetes.io" class="mailing-list"><span>Forum</span></a>
                <a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
            </div>
            <div>
                <a href="../../../../getting-started-guides/index.html" class="button">Get Kubernetes</a>
                <a href="https://git.k8s.io/community/contributors/guide" class="button">Contribute</a>
            </div>
        </div>
        <div id="miceType" class="center">
            &copy; 2018 The Kubernetes Authors | Documentation Distributed under <a href="https://git.k8s.io/website/LICENSE" class="light-text">CC BY 4.0</a>
        </div>
        <div id="miceType" class="center">
            Copyright &copy; 2018 The Linux Foundation&reg;. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our <a href="https://www.linuxfoundation.org/trademark-usage" class="light-text">Trademark Usage page</a>
        </div>
    </main>
</footer>

		<button class="flyout-button" onclick="kub.toggleToc()"></button>

<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-36037335-10', 'auto');
ga('send', 'pageview');


(function () {
    window.addEventListener('DOMContentLoaded', init)

        
        function init() {
            window.removeEventListener('DOMContentLoaded', init)
                hideNav()
        }

    function hideNav(toc){
        if (!toc) toc = document.querySelector('#docsToc')
        if (!toc) return
            var container = toc.querySelector('.container')

                
                if (container) {
                    if (container.childElementCount === 0 || toc.querySelectorAll('a.item').length === 1) {
                        toc.style.display = 'none'
                            document.getElementById('docsContent').style.width = '100%'
                    }
                } else {
                    requestAnimationFrame(function () {
                        hideNav(toc)
                    })
                }
    }
})();
</script>



	</body>
</html>